Crate serde_yml

Serde YML (a fork of Serde YAML)

A Rust library for using the Serde serialization framework with data in YAML file format. This project, has been renamed to Serde YML to avoid confusion with the original Serde YAML crate which is now archived and no longer maintained.

Credits and Acknowledgements

This library is a continuation of the excellent work done by David Tolnay and the maintainers of the serde-yaml library.

While Serde YML started as a fork of serde-yaml, it has now evolved into a separate library with its own goals and direction in mind and does not intend to replace the original serde-yaml crate.

If you are currently using serde-yaml in your projects, we recommend carefully evaluating your requirements and considering the stability and maturity of the original library as well as looking at the features and improvements offered by other YAML libraries in the Rust ecosystem.

I would like to express my sincere gratitude to David Tolnay and the serde-yaml team for their valuable contributions to the Rust community and for inspiring this project.

Features

• Serialization and deserialization of Rust data structures to/from YAML format
• Support for custom structs and enums using Serde’s derive macros
• Handling of YAML’s !tag syntax for representing enum variants
• Direct access to YAML values through the Value type and related types like Mapping and Sequence
• Comprehensive error handling with Error, Location, and Result types
• Serialization to YAML using to_string and to_writer functions
• Deserialization from YAML using from_str, from_slice, and from_reader functions
• Customizable serialization and deserialization behavior using Serde’s #[serde(with = ...)] attribute
• Support for serializing/deserializing enums using a YAML map with a single key-value pair through the singleton_map module
• Recursive application of singleton_map serialization/deserialization to all enums within a data structure using the singleton_map_recursive module
• Serialization and deserialization of optional enum fields using the singleton_map_optional module
• Handling of nested enum structures with optional inner enums using the singleton_map_recursive module
• Customization of serialization and deserialization logic for enums using the singleton_map_with module and custom helper functions

Rust Version Compatibility

This library is compatible with Rust 1.60 and above.

Installation

Add the following dependency to your Cargo.toml file:

[dependencies]
serde_yml = "0.0.11"

Usage

Serde YML offers a straightforward and intuitive API for working with YAML data in Rust. Here’s a quick example of how to serialize and deserialize a Rust type:

use serde::{Serialize, Deserialize};

#[derive(Serialize, Deserialize,Debug,PartialEq)]
struct Point {
    x: f64,
    y: f64,
}

fn main() -> Result<(), serde_yml::Error> {
    let point = Point { x: 1.0, y: 2.0 };

    // Serialize to YAML
    let yaml = serde_yml::to_string(&point)?;
    assert_eq!(yaml, "x: 1.0\n'y': 2.0\n");

    // Deserialize from YAML
    let deserialized_point: Point = serde_yml::from_str(&yaml)?;
    assert_eq!(point, deserialized_point);

    Ok(())
}

Examples

Serde YML provides a set of comprehensive examples to demonstrate its usage and capabilities. You can find them in the examples directory of the project.

To run the examples, clone the repository and execute the following command in your terminal from the project root directory:

cargo run --example example

The examples cover various scenarios, including serializing and deserializing structs, enums, optional fields, custom structs, and more.

Re-exports

• pub use crate::de::from_reader;
• pub use crate::de::from_slice;
• pub use crate::de::from_str;
• pub use crate::de::Deserializer;
• pub use crate::modules::error::Error;
• pub use crate::modules::error::Location;
• pub use crate::modules::error::Result;
• pub use crate::ser::to_string;
• pub use crate::ser::to_writer;
• pub use crate::ser::Serializer;
• pub use crate::ser::State;

Modules

• de
  The de module contains the library’s YAML deserializer.
• libyml
  The libyml module contains the library’s YAML parser and emitter.
• loader
  The loader module contains the Loader type for YAML loading.
• macros
  The macros module contains functions for generating macros.
• mapping
  The mapping module contains the Mapping type for YAML mappings. A YAML mapping and its iterator types.
• modules
  The modules module contains the library’s modules.
• number
  The number module contains the Number type for YAML numbers.
• ser
  The ser module contains the library’s YAML serializer. YAML Serialization
• utilities
  The utilities module contains utility functions for the library.
• value
  The value module contains the Value type for YAML values. The Value enum, a loosely typed way of representing any valid YAML value.
• with
  The with module contains the With type for YAML values. Customizations to use with Serde’s #[serde(with = …)] attribute.

Macros

• from_number
  Macro from_number to implement conversion from number types to Value.
• generate_file
  A macro that generates a file based on a provided value, a generator function, and an optional custom serializer.
• macro_check_directory
  macro_check_directory Macro
• macro_cleanup_directories
  macro_cleanup_directories Macro
• macro_create_directories
  macro_create_directories Macro
• macro_get_field
  Macro to generate a function that retrieves a field value from a JSON file.
• macro_replace_placeholder
  Replaces placeholders in a given line with corresponding values from the provided parameters.
• nested_singleton_map_deserialize
  A macro that deserializes a nested singleton map from a YAML format.
• nested_singleton_map_serialize
  A macro that serializes a nested singleton map to a YAML format.
• partialeq_numeric
  A macro that generates implementations of the PartialEq trait for primitive numeric types and Value based on the specified conversion method and base type.

Structs

• Mapping
  A YAML mapping in which the keys and values are both serde_yml::Value.
• Number
  Represents a YAML number, whether integer or floating point.

Enums

• Value
  Represents any valid YAML value.

Traits

• Index
  A type that can be used to index into a serde_yml::Value. See the get and get_mut methods of Value.

Functions

• from_value
  Interpret a serde_yml::Value as an instance of type T.
• to_value
  Converts a serializable value into a serde_yml::Value.

Type Aliases

• Sequence
  A YAML sequence in which the elements are serde_yml::Value.